Tangoe ServiceNow API

(0 reviews)

Case API

The case API allows you to:

create a case on Tangoe ServiceNow instance
update cases which is not closed at Tangoe side
retrieve case details

type	endpoint
POST	/api/tango/v1/integrations/cases	Create a case
PATCH	/api/tango/v1/integrations/cases/{number}	Update a non-closed case
GET	/api/tango/v1/integrations/cases	Retrieve the list of cases
GET	/api/tango/v1/integrations/cases/{number}	Retrieve the case by case number
DELETE	/api/tango/v1/integrations/cases/{number}	Cancel a non-closed case

Create Cases

Creating a case implies registering a case on Tangoe ServiceNow API with valid and required parameters. When valid request body parameters are passed to the API, the Tangoe ServiceNow API system will validate the data and see if calling user has proper access to create the case on its instance. After all validation is completed, a case is registered on Tangoe ServiceNow system and a success message is sent back instantly.

When a case is successfully created, the API returns a result key containing the full response payload, which typically contains keys like id, number, status.

Example Request and Response

Note: - Below are example requests and responses, please use the appropriate base URL.

REQUEST

curl "https://tangoe.service-now.com/api/tango/v1/integrations/cases" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--user 'username':'password' \
--data '{case_object}'

sample case_object:

{
  "short_description": "TEST This is a test case short description",
  "description": "TEST This is a test case description",
  "entitlement_id": "7594faefdb9d3f040e08fce9af961964",
  "priority": "3",
  "correlation_id": "UMCCASE12345",
  "correlation_display": "INCxxx12345",
  "contact_email":"john.doe@tangoe.com",
  "additional_contacts": "user.name1@company.com, user.name2@company.com",
  "callback": {
    "callback_url": "https://cust-snow.com/api/customer/callback",
    "callback_type": "POST",
    "callback_auth_type": "basic",
    "callback_auth_user": "username",
    "callback_auth_password": "password"
  }
}

RESPONSE

HTTP/1.1 201 OK
Content-Type: application/json
{
  "result": {
    "id": "9e641634db97c450a813fd651d96194f",
    "number": "CS0618457",
    "status": "inserted"
  }
}

Request Parameters

parameters	required/optional	description
short_description	required	Short description text, this is a required field
description	required	Description text represents detailed description of the issue/case. This is a required field.
entitlement_id	optional	The entitlement id affects how the case is handled by Tangoe's support staff. A separate API is available to determine the valid values for your organization, and it is critical the correct value be supplied here. Blanks are accepted but may result in significantly slower handling times for your case. Invalid ids will generate exceptions and cause the payload to be rejected. NOTE: - This parameter cannot be updated via API once set.
correlation_id	optional	This can be used to track any additional case identification at your end, the back-end value set here will be saved as it is and can be retrieved via GET API down the line.
correlation_display	optional	This can be used to track any additional case identification at your end, the front-end value set here will be saved as it is and can be retrieved via GET API down the line.
contact_email	required	Primary contact email ID on the case, this has to be a valid email ID at Tangoe side or else default contact email id registered for your account will be populated on the case. NOTE: -This parameter cannot be updated via API once set.
priority	optional	Priority of the case, It can be one of the following 1, 2, 3, 4, 5. The mapping for the same is given below: 1 - System Outage 2 - Critical 3 - High 4 - Medium 5 - Low if this parameter is not set, the default priority would be set on the case.
additional_contacts	optional	Multiple comma separated email ID can be set on the case, these contacts would get any notification populated on the case based on the eligibility for your account. NOTE: - This parameter cannot be updated via API once set.
callback	optional	Set this object to subscribe to update events on the case triggered by Tangoe agents. If this object is set properly, the Tangoe ServiceNow instance will attempt an API callback whenever key fields are updated on the case. The callback payload will contain the relevant case details as shown in the Callback section of this document. If no callback object is set, you can still retrieve case details at any time, but changes will not be pushed to you. If the callback object is set, then all the below mentioned attributes are mandatory and appropriate value should be set. callback_url : URL to which the callback should be made. callback_type : HTTP method need to be used when calling `callback_url`. example: `POST`, `PUT`, `PATCH`. callback_auth_type : This can be either `basic` or `no-auth`, this should be set to `basic` if basic authentication is need to be performed while calling the callback_url. We currently support only basic authentication. callback_auth_user : if `callback_auth_type = "basic"`, set this value with appropriate user name which need to be used while calling the `callback_url` else set this to empty string. callback_auth_password : if `callback_auth_type = "basic"`, set this value with appropriate user password which need to be used while calling the `callback_url`, else set this to empty string.

Response Attributes

attribute	description
id	Unique record ID
number	Case number created by Tangoe. This number should always be used to query Tangoe ServiceNow Case GET/UPDATE API's
status	indicates the status of the current request

Modifying Cases

If a case is open or pending in Tangoe ServiceNow system, certain attributes of it can be modified.

It is important to send the appropriate case number when you need to modify the specific case. When a case is successfully updated, the API returns a result key containing the full response payload, which typically contains keys like id, number, status.

Example Request and Response

Note: - Below are example requests and responses, please use the appropriate base URL

REQUEST

curl "https://tangoe.service-now.com/api/tango/v1/integrations/cases/{number}" \
--request PATCH \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--user 'username':'password' \
--data '{case_update_object}'

sample case_update_object:

{
  "description": "TEST:This is a test case and updated on dd-mm-yyyy hh:mm",
  "priority": "2",
  "correlation_id": "UMCCASE12345-1",
  "correlation_display": "INCxxx12345",
  "callback": {
    "callback_url": "https://cust-snow.com/api/customer/callback",
    "callback_type": "PUT",
    "callback_auth_type": "basic",
    "callback_auth_user": "username",
    "callback_auth_password": "updated-password"
  }
}

RESPONSE

HTTP/1.1 200 OK
Content-Type: application/json
{
  "result": {
    "id": "9e641634db97c450a813fd651d96194f",
    "number": "CS0618457",
    "status": "updated"
  }
}

Note: - At least one of the below parameters should be set in the request body to update the case appropriately. If none of the below parameters need to be updated on the Tangoe side of the case, please do not request this API.

Request Parameters

parameters	required/optional	description
short_description	required	Short description text, this is a required field
description	required	Description text represents detailed description of the issue/case. This is a required field.
entitlement_id	optional	The entitlement id affects how the case is handled by Tangoe's support staff. A separate API is available to determine the valid values for your organization, and it is critical the correct value be supplied here. Blanks are accepted but may result in significantly slower handling times for your case. Invalid ids will generate exceptions and cause the payload to be rejected. NOTE: - This parameter cannot be updated via API once set.
correlation_id	optional	This can be used to track any additional case identification at your end, the back-end value set here will be saved as it is and can be retrieved via GET API down the line.
correlation_display	optional	This can be used to track any additional case identification at your end, the front-end value set here will be saved as it is and can be retrieved via GET API down the line.
contact_email	optional	Primary contact email ID on the case, this has to be a valid email ID at Tangoe side or else default contact email id registered for your account will be populated on the case. NOTE: -This parameter cannot be updated via API once set.
priority	optional	Priority of the case, It can be one of the following 1, 2, 3, 4, 5. The mapping for the same is given below: 1 - System Outage 2 - Critical 3 - High 4 - Medium 5 - Low if this parameter is not set, the default priority would be set on the case.
additional_contacts	optional	Multiple comma-separated email ID can be set on the case, these contacts would get any notification populated on the case based on the eligibility for your account. NOTE: - This parameter cannot be updated via API once set.
callback	optional	Set this object to subscribe to update events on the case triggered by Tangoe agents. If this object is set properly, the Tangoe ServiceNow instance will attempt an API callback whenever key fields are updated on the case. The callback payload will contain the relevant case details as shown in the Callback section of this document. If no callback object is set, you can still retrieve case details at any time, but changes will not be pushed to you. If the callback object is set, then all the below-mentioned attributes are mandatory and appropriate value should be set. callback_url : URL to which the callback should be made. callback_type : HTTP method need to be used when calling `callback_url`. example: `POST`, `PUT`, `PATCH`. callback_auth_type : This can be either `basic` or `no-auth`, this should be set to `basic` if basic authentication is need to be performed while calling the callback_url. We currently support only basic authentication. callback_auth_user : if `callback_auth_type = "basic"`, set this value with appropriate user name which need to be used while calling the `callback_url` else set this to empty string. callback_auth_password : if `callback_auth_type = "basic"`, set this value with appropriate user password which need to be used while calling the `callback_url`, else set this to empty string.

Response Attributes

attribute	description
id	Unique record ID
number	Case number created by Tangoe. This number should always be used to query Tangoe ServiceNow Case GET/UPDATE API's
status	indicates the status of the current request

Retrieving Cases

Cases from Tangoe ServiceNow can be retrieved individually by passing the case number as an attribute or in bulk using query parameters. Once the cases are created in the system, irrespective of its status, it can be queried and retrieved using the GET API.

Query Parameters

parameter	required/optional	description
limit	optional	The maximum number of results returned per page (default: 10)
offset	optional	Offset option specifies the number of items in the queried collection to be skip
include_comments	optional	Set this flag to “true” if "comments" array is needed in the response, Default(false)

|sysparm_query |optional |Optional Query can be passed to filter the records appropriately. See sysparm_query section for additional details |

Response Attributes

attribute	description
number	case number created by Tangoe
id	unique record ID
state	current state of the case in Tangoe ServiceNow system. It can be one of the following 1, 3, 5, 6, 7, 10, -5, -10.The mapping for the same is given below : 1 - New 3 - Closed 5 - Assigned 6 - Complete/Resolved 7 - Cancelled 10 - Work In Progress -5 - On Hold -10 - Reassigned
priority	priority of the case, It can be one of the following 1, 2, 3, 4, 5. The mapping for the same is given below: 1 - System Outage 2 - Critical 3 - High 4 - Medium 5 - Low
short_description	short description text
description	description text represents a detailed description of the issue/case.
correlation_id	correlation id set by API consumer via Create or Update API request
correlation_display	correlation display set by API consumer via Create or Update API request
contact_email	primary contact email ID on the case
created_on	case creation date
updated_on	case last update on
close_code	case close code set by the Tangoe support agent while resolving the case
close_notes	case close notes set by the Tangoe support agent while resolving the case
completion_date_time	case completion date time
resolved_at	case resolution date time

Example Request and Response

Note: - Below are example requests and responses, please use the appropriate base URL.

REQUEST 1 - Retrieve case by case number

curl "https://tangoe.service-now.com/api/tango/v1/integrations/cases/{number}" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

RESPONSE

HTTP/1.1 200 OK
Content-Type: application/json
{
  "result": {
    "number": "CS0618457",
    "id": "9e641634db97c450a813fd651d96194f",
    "state": "3",
    "priority": "3",
    "short_description": "TEST :- This is a test ticket",
    "description": "TEST :- This is a test ticket updated on 29Feb2020",
    "correlation_id": "",
    "correlation_display": "",
    "contact_email": "DoNotReply@Tangoe.com",
    "created_on": "2020-02-28 19:06:23",
    "updated_on": "2020-02-28 20:20:15",
    "close_code": "Closed Normal",
    "close_notes": "completed the task",
    "completion_date_time": "2020-02-28 20:19:01",
    "resolved_at": "2020-02-28 20:19:01"
  }
}

REQUEST 2 - Retrieve first 20 cases

curl "https://tangoe.service- now.com/api/tango/v1/integrations/cases?limit=20=0" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

RESPONSE

HTTP/1.1 200 OK
Content-Type: application/json
{
  "result": [ {
    "number": "CS0618465",
    "id": "d194729ddb174850a813fd651d9619db",
    "state": "1",
    "priority": "2",
    "short_description": "TEST :- This is a test ticket",
    "description": "TEST :- This is a test ticket and updated on 03 IST ",
    "correlation_id": "UMCCASE12345-1",
    "correlation_display": "INCxxx12345",
    "contact_email": "DoNotReply@Tangoe.com",
    "created_on": "2020-03-01 10:43:55",
    "updated_on": "2020-03-01 16:59:31",
    "close_code": "",
    "close_notes": "",
    "completion_date_time": "",
    "resolved_at": ""
  },
  {
    "number": "CS0618457",
    "id": "9e641634db97c450a813fd651d96194f",
    "state": "3",
    "priority": "3",
    "short_description": "TEST This is a test ticket",
    "description": "TEST This is a test ticket updated on 29Feb2020",
    "correlation_id": "",
    "correlation_display": "",
    "contact_email": "DoNotReply@Tangoe.com",
    "created_on": "2020-02-28 19:06:23",
    "updated_on": "2020-02-28 20:20:15",
    "close_code": "Closed Normal",
    "close_notes": "completed the task",
    "completion_date_time": "2020-02-28 20:19:01",
    "resolved_at": "2020-02-28 20:19:01"
  },
  {...} // record skipped for readability purposes ]
}

REQUEST 3 - Retrieve case with comments

curl "https://tangoe.service-now.com/api/tango/v1/integrations/cases /CS0618457?include_comments=true" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

RESPONSE

HTTP/1.1 200 OK
Content-Type: application/json
{
  "result": {
    "number": "CS0618457",
    "id": "9e641634db97c450a813fd651d96194f",
    "state": "3",
    "priority": "3",
    "short_description": "TEST :- This is a test ticket",
    "description": "TEST :- This is a test ticket updated on 29Feb2020",
    "correlation_id": "",
    "correlation_display": "",
    "contact_email": "DoNotReply@Tangoe.com",
    "comments": [
      {
        "id": "aa15a234dbd7c450a813fd651d961998",
        "comment": "some comment value again",
        "created_on": "2020-02-28 20:19:18",
        "created_by": "john.dow@tangoe.com"
      },
      {
        "id": "a9646af0dbd7c450a813fd651d9619e0",
        "comment": "some comment value later",
        "created_on": "2020-02-28 20:16:14",
        "created_by": "john.dow@tangoe.com"
      },
      {
        "id": "4a2466f0dbd7c450a813fd651d96195c",
        "comment": "some comment value now",
        "created_on": "2020-02-28 20:15:11",
        "created_by": "steve.dow@tangoe.com"
      }
    ],
    "created_on": "2020-02-28 19:06:23",
    "updated_on": "2020-02-28 20:20:15",
    "close_code": "Closed Normal",
    "close_notes": "completed the task",
    "completion_date_time": "2020-02-28 20:19:01",
    "resolved_at": "2020-02-28 20:19:01"
  }
}

REQUEST 4 - Retrieve cases created after a particular date using a standard ServiceNow encoded query string in the sysparm_query parameter

Info - query used: - sysparm_query=sys_created_onRELATIVEGE@minute@ago@45
Note: - Javascript cannot be used to query the records, all javascript query string within the Queryparams will be ignored.

curl "https://tangoe.service-now.com/api/tango/v1/integrations/cases? limit=2&offset=0&sysparm_query=sys_created_onRELATIVEGE@minute@ago@45" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

RESPONSE

HTTP/1.1 200 OK
Content-Type: application/json
{
  "result": [
    {
      "number": "CS0618465",
      "id": "d194729ddb174850a813fd651d9619db",
      "state": "1",
      "priority": "2",
      "short_description": "TEST :- This is a test ticket",
      "description": "TEST :- This is a test ticket and updated on 03-Mar-
2020 9:53 PM IST ",
      "correlation_id": "UMCCASE12345-1",
      "correlation_display": "INCxxx12345",
      "contact_email": "DoNotReply@Tangoe.com",
      "created_on": "2020-03-01 10:43:55",
      "updated_on": "2020-03-01 16:59:31",
      "close_code": "",
      "close_notes": "",
      "completion_date_time": "",
      "resolved_at": ""
    },
    {

      "number": "CS0618457",
      "id": "9e641634db97c450a813fd651d96194f",
      "state": "3",
      "priority": "3",
      "short_description": "TEST :- This is a test ticket",
      "description": "TEST :- This is a test ticket updated on 29Feb2020",
      "correlation_id": "",
      "correlation_display": "",
      "contact_email": "DoNotReply@Tangoe.com",
      "created_on": "2020-02-28 19:06:23",
      "updated_on": "2020-02-28 20:20:15",
      "close_code": "Closed Normal",
      "close_notes": "completed the task",
      "completion_date_time": "2020-02-28 20:19:01",
      "resolved_at": "2020-02-28 20:19:01"
    }
  ]
}

Cancel a Case

As long as a case remains open (in Open or any of the other pending states in the system), it can be canceled.

Query Parameters

parameter	required/optional	description
cancel_type	required	It should be either in 1 or 2, this value governs how the cancel request need to be handled, mapping for both the values are given below. 1 = Cancelled 2 = Closed Out of Scope

Response Attributes

attribute	description
id	Unique record ID
number	Case number created by Tangoe. This number should always be used to query Tangoe ServiceNow Case GET/UPDATE API's
status	indicates the status of the current request

Example Request and Response

Note: - Below are example requests and responses, please use the appropriate base URL.

REQUEST

curl "https://tangoe.service-now.com/api/tango/v1/integrations/cases/CS0665791" \
--request DELETE \
--header "Accept:application/json" \
--user 'username':'password'

RESPONSE

HTTP/1.1 200 OK
Content-Type: application/json
{
  "result": {
    "id": "6abb8cd1dbd51810d80b5a58dc961900",
    "number": "CS0665791",
    "status": "updated"
  }
}

Case API

Create Cases

Example Request and Response

Modifying Cases

Example Request and Response

Retrieving Cases

Example Request and Response

Cancel a Case

Example Request and Response

Reviews